@verajs/renderer 0.2.2 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +711 -225
- package/dist/development/vera-renderer-elements.d.ts +39 -0
- package/dist/development/vera-renderer-elements.d.ts.map +1 -0
- package/dist/development/vera-renderer-elements.js +193 -0
- package/dist/development/vera-renderer-elements.js.map +1 -0
- package/dist/development/vera-renderer-hydrate-slots.d.ts +94 -0
- package/dist/development/vera-renderer-hydrate-slots.d.ts.map +1 -0
- package/dist/development/vera-renderer-hydrate-slots.js +325 -0
- package/dist/development/vera-renderer-hydrate-slots.js.map +1 -0
- package/dist/development/vera-renderer-hydration.d.ts +332 -0
- package/dist/development/vera-renderer-hydration.d.ts.map +1 -0
- package/dist/development/vera-renderer-hydration.js +864 -0
- package/dist/development/vera-renderer-hydration.js.map +1 -0
- package/dist/development/vera-renderer-keyed.d.ts +25 -8
- package/dist/development/vera-renderer-keyed.d.ts.map +1 -1
- package/dist/development/vera-renderer-keyed.js +843 -268
- package/dist/development/vera-renderer-keyed.js.map +1 -1
- package/dist/development/vera-renderer-multi-window.d.ts +5 -0
- package/dist/development/vera-renderer-multi-window.d.ts.map +1 -0
- package/dist/development/vera-renderer-multi-window.js +40 -0
- package/dist/development/vera-renderer-multi-window.js.map +1 -0
- package/dist/development/vera-renderer-namespaces.d.ts +64 -0
- package/dist/development/vera-renderer-namespaces.d.ts.map +1 -0
- package/dist/development/vera-renderer-namespaces.js +94 -0
- package/dist/development/vera-renderer-namespaces.js.map +1 -0
- package/dist/development/vera-renderer-native-elements.d.ts +13 -0
- package/dist/development/vera-renderer-native-elements.d.ts.map +1 -0
- package/dist/development/vera-renderer-native-elements.js +231 -0
- package/dist/development/vera-renderer-native-elements.js.map +1 -0
- package/dist/development/vera-renderer-portal.d.ts +29 -0
- package/dist/development/vera-renderer-portal.d.ts.map +1 -0
- package/dist/development/vera-renderer-portal.js +167 -0
- package/dist/development/vera-renderer-portal.js.map +1 -0
- package/dist/development/vera-renderer-profiler.d.ts +48 -96
- package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
- package/dist/development/vera-renderer-profiler.js +2423 -2140
- package/dist/development/vera-renderer-profiler.js.map +1 -1
- package/dist/development/vera-renderer-slots.d.ts +88 -92
- package/dist/development/vera-renderer-slots.d.ts.map +1 -1
- package/dist/development/vera-renderer-slots.js +1834 -1237
- package/dist/development/vera-renderer-slots.js.map +1 -1
- package/dist/development/vera-renderer-spread.d.ts +7 -41
- package/dist/development/vera-renderer-spread.d.ts.map +1 -1
- package/dist/development/vera-renderer-spread.js +539 -477
- package/dist/development/vera-renderer-spread.js.map +1 -1
- package/dist/development/vera-renderer-tag.d.ts +12 -3
- package/dist/development/vera-renderer-tag.d.ts.map +1 -1
- package/dist/development/vera-renderer-tag.js +671 -513
- package/dist/development/vera-renderer-tag.js.map +1 -1
- package/dist/development/vera-renderer-until.d.ts +24 -0
- package/dist/development/vera-renderer-until.d.ts.map +1 -0
- package/dist/development/vera-renderer-until.js +83 -0
- package/dist/development/vera-renderer-until.js.map +1 -0
- package/dist/development/vera-renderer.d.ts +48 -96
- package/dist/development/vera-renderer.d.ts.map +1 -1
- package/dist/development/vera-renderer.js +2400 -2104
- package/dist/development/vera-renderer.js.map +1 -1
- package/dist/vera-renderer-elements.min.js +2 -0
- package/dist/vera-renderer-elements.min.js.map +1 -0
- package/dist/vera-renderer-hydrate-slots.min.js +2 -0
- package/dist/vera-renderer-hydrate-slots.min.js.map +1 -0
- package/dist/vera-renderer-hydration.min.js +3 -0
- package/dist/vera-renderer-hydration.min.js.map +1 -0
- package/dist/vera-renderer-keyed.min.js +1 -1
- package/dist/vera-renderer-keyed.min.js.map +1 -1
- package/dist/vera-renderer-multi-window.min.js +2 -0
- package/dist/vera-renderer-multi-window.min.js.map +1 -0
- package/dist/vera-renderer-namespaces.min.js +2 -0
- package/dist/vera-renderer-namespaces.min.js.map +1 -0
- package/dist/vera-renderer-native-elements.min.js +2 -0
- package/dist/vera-renderer-native-elements.min.js.map +1 -0
- package/dist/vera-renderer-portal.min.js +2 -0
- package/dist/vera-renderer-portal.min.js.map +1 -0
- package/dist/vera-renderer-slots.min.js +1 -1
- package/dist/vera-renderer-slots.min.js.map +1 -1
- package/dist/vera-renderer-spread.min.js +1 -1
- package/dist/vera-renderer-spread.min.js.map +1 -1
- package/dist/vera-renderer-tag.min.js +1 -1
- package/dist/vera-renderer-tag.min.js.map +1 -1
- package/dist/vera-renderer-until.min.js +2 -0
- package/dist/vera-renderer-until.min.js.map +1 -0
- package/dist/vera-renderer.min.js +1 -1
- package/dist/vera-renderer.min.js.map +1 -1
- package/package.json +52 -9
- package/dist/development/vera-renderer-hydrate.d.ts +0 -147
- package/dist/development/vera-renderer-hydrate.d.ts.map +0 -1
- package/dist/development/vera-renderer-hydrate.js +0 -3136
- package/dist/development/vera-renderer-hydrate.js.map +0 -1
- package/dist/vera-renderer-hydrate.min.js +0 -2
- package/dist/vera-renderer-hydrate.min.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @verajs/renderer
|
|
2
2
|
|
|
3
|
-
The DOM renderer for VeraJS — <!--size:renderer.gzip-->
|
|
3
|
+
The DOM renderer for VeraJS — <!--size:renderer.gzip-->5.69 KB<!--/size:renderer.gzip--> gzipped,
|
|
4
4
|
no dependencies, no build step required.
|
|
5
5
|
|
|
6
6
|
Tagged templates parse once and clone; every render after the first walks only the value slots, so
|
|
@@ -18,7 +18,7 @@ there is no second call to make.
|
|
|
18
18
|
|
|
19
19
|
<!-- recipe -->
|
|
20
20
|
```js
|
|
21
|
-
import { init, createStore,
|
|
21
|
+
import { init, createStore, wire, html } from '@verajs/core';
|
|
22
22
|
import { renderer } from '@verajs/renderer';
|
|
23
23
|
|
|
24
24
|
wire([renderer]);
|
|
@@ -27,9 +27,10 @@ customElements.define(
|
|
|
27
27
|
'click-counter',
|
|
28
28
|
class extends HTMLElement {
|
|
29
29
|
connectedCallback() {
|
|
30
|
-
init(this,
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
init({ host: this, shadow: 'open' }, () => {
|
|
31
|
+
const state = createStore({ count: 0 });
|
|
32
|
+
return () => html`<button @click=${() => state.count++}>Clicked ${state.count} times</button>`;
|
|
33
|
+
});
|
|
33
34
|
}
|
|
34
35
|
}
|
|
35
36
|
);
|
|
@@ -37,13 +38,21 @@ customElements.define(
|
|
|
37
38
|
document.body.append(document.createElement('click-counter'));
|
|
38
39
|
```
|
|
39
40
|
|
|
40
|
-
Without it, core has no renderer at all:
|
|
41
|
+
Without it, core has no renderer at all: a component warns once (in every build) and puts
|
|
41
42
|
nothing on the page. `@event`, `.prop` and `?bool` bindings are the first things to go missing.
|
|
42
43
|
|
|
44
|
+
**One renderer serves one core.** A renderer connects to the core whose `wire` it was last handed. On
|
|
45
|
+
a CDN page with two apps that load DIFFERENT copies of core (two versions) but the SAME renderer
|
|
46
|
+
URL, the second app's `wire([renderer])` takes the renderer over, and the first app's renders lose
|
|
47
|
+
their tracking. The renderer says so when it happens — `[vera] renderer-two-cores` (the code's entry
|
|
48
|
+
at `verajs.dev/e/renderer-two-cores` explains it). Give each app its own renderer URL beside its own core,
|
|
49
|
+
or share one core between them. (Under a bundler, or two apps on the same core URL, there is one
|
|
50
|
+
core and nothing to do.)
|
|
51
|
+
|
|
43
52
|
### `renderInto(result, container)`
|
|
44
53
|
|
|
45
54
|
The same write, called directly — no reactivity, no lifecycle, no custom element. `wire([renderer])`
|
|
46
|
-
registers exactly this function, so
|
|
55
|
+
registers exactly this function, so every component's render ends up here; calling it yourself is how
|
|
47
56
|
you draw into a plain node, which is the incremental-adoption path and the way to test a template
|
|
48
57
|
without spinning up an element.
|
|
49
58
|
|
|
@@ -54,14 +63,28 @@ import { html } from '@verajs/core';
|
|
|
54
63
|
renderInto(html`<p>${count}</p>`, document.querySelector('#app'));
|
|
55
64
|
```
|
|
56
65
|
|
|
57
|
-
It **owns its own range and nothing else**: the first call anchors a root part
|
|
58
|
-
appends, later calls with the same container reuse that part and walk only the value slots, and
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
66
|
+
It **owns its own range and nothing else**: the first call anchors a root part between two markers
|
|
67
|
+
it appends, later calls with the same container reuse that part and walk only the value slots, and
|
|
68
|
+
content before and after that range stays — whatever was already in the container, and whatever other
|
|
69
|
+
code (a script, a browser extension) appends to it later, survives every re-render, a template swap
|
|
70
|
+
included. It is not reactive — call it again to update, or use a component and let a store do it.
|
|
71
|
+
|
|
72
|
+
**A component's shadow root is different: by default its template owns it** (`foreignNodes: 'drop'`). Foreign nodes
|
|
73
|
+
— nodes placed in a component's root by anything other than its own template — are left alone by an ordinary
|
|
74
|
+
re-render, and cleared with everything else when the template changes (a different template, text, a list, nothing);
|
|
75
|
+
development says so the first time. The root then needs no marker comments, which makes every shadow component
|
|
76
|
+
cheaper to create. A component that must keep what something else puts in its root says
|
|
77
|
+
`init({ host: this, shadow: 'open', foreignNodes: 'preserve' }, setup)`; `wire([renderer({ foreignNodes: 'preserve' })])`
|
|
78
|
+
makes that every component's default. Either way it covers component roots only: a container handed to `renderInto`
|
|
79
|
+
(`document.body`, `#app`) always keeps foreign nodes, as above. A shadow root that already holds something at its first
|
|
80
|
+
render (a server's declarative root, styles' `<style>` fallback) keeps its markers too. Light-DOM component roots are
|
|
81
|
+
not affected yet. One corner: a `hold()` at an owned root parks the root's whole content with the branch it parks, so
|
|
82
|
+
a foreign node there goes away with that branch and comes back with it rather than being dropped — as with a plain
|
|
83
|
+
element whose whole content is one binding.
|
|
84
|
+
|
|
85
|
+
It was named `render` until 0.2.0, which collided with core's `render` of the time — a different function, with
|
|
86
|
+
a different arity, that declared a *reactive* template and committed a component's setup (a setup now returns its
|
|
87
|
+
render instead). Both were public and both were documented, so a reader who knew one misread the other.
|
|
65
88
|
|
|
66
89
|
## Bindings
|
|
67
90
|
|
|
@@ -74,12 +97,23 @@ public and both are documented, so a reader who knew one misread the other.
|
|
|
74
97
|
| `<p ?hidden=${value}>` | boolean attribute, present when truthy |
|
|
75
98
|
| `<input !checked=${value}>` | property written from the **live DOM** rather than from what the binding last wrote — see below |
|
|
76
99
|
| `<button @click=${fn}>` | event listener. An object with a `handleEvent` method works too — `addEventListener` takes both |
|
|
77
|
-
| `<button onClick=${fn}>` | the same thing, React-style. Strictly `on` + a capital
|
|
100
|
+
| `<button onClick=${fn}>` | the same thing, React-style. Strictly `on` + a capital. A STATIC `onclick="…"` stays a plain attribute (yours, greppable); a BOUND `onclick=${…}` runs its value as code, so it is **refused** — in templates, in spread and on the server alike |
|
|
78
101
|
| `<input ${fn}>` | element ref: a function is called with the element |
|
|
79
|
-
| `<input ${obj}>` | element ref: an object gets the element assigned to `.value`, so core's `
|
|
102
|
+
| `<input ${obj}>` | element ref: an object gets the element assigned to `.value`, so core's `signal()` works here |
|
|
80
103
|
| `<input ${spread(props)}>` | names resolved at runtime — see [`/spread`](#verajsrendererspread) |
|
|
81
104
|
|
|
82
|
-
A ref runs once per **distinct value**, not once per render
|
|
105
|
+
A ref runs once per **distinct value**, not once per render — and **after its render pass**, once the
|
|
106
|
+
pass's DOM exists: the element is inserted, a custom element is upgraded, and it belongs to its own
|
|
107
|
+
document, so a ref can measure it, focus it, or read its window. Within a pass, refs run in commit order
|
|
108
|
+
— document pre-order, so an element's ref runs before the refs inside it and before its next sibling's —
|
|
109
|
+
after the pass's `<select>` values are set; a
|
|
110
|
+
ref replaced or removed before its turn is handed nothing. A ref runs **untracked**: what it reads never
|
|
111
|
+
subscribes the component that rendered it — a ref captures an element, it is not a dependency.
|
|
112
|
+
|
|
113
|
+
**Replacing a ref tells the old one first.** Changing `${a}` to `${b}` calls `a(null)` at once and hands `b`
|
|
114
|
+
the element after the pass; changing it to `${null}` calls `a(null)`. A `{ value }` ref is emptied the same way.
|
|
115
|
+
A value that applies itself (`_$apply$`, such as a spread) is never written to — it owns its own lifecycle,
|
|
116
|
+
so a position switching from a spread to a ref leaves the spread's keys as they were.
|
|
83
117
|
|
|
84
118
|
**A ref is released when its subtree is rendered away, and not when its component is removed from
|
|
85
119
|
the document.** Toggling `${show ? html`<i ${box}>` : 'gone'}` sets `box.value` back to `null` (and
|
|
@@ -98,6 +132,13 @@ object with no `handleEvent` — is inert, and **development names it at the bin
|
|
|
98
132
|
only ever called when a user clicks, so left unchecked the mistake surfaces at a point where nothing
|
|
99
133
|
on the stack says where the value came from.
|
|
100
134
|
|
|
135
|
+
**A handler never subscribes the hook that happens to be running.** An effect that fires an event
|
|
136
|
+
synchronously — `button.click()`, `input.focus()`, `dispatchEvent` — runs the handler inside itself, and
|
|
137
|
+
the handler's reads used to subscribe that effect: a handler doing `state.count++` re-ran the effect on
|
|
138
|
+
every later click. Every listener Vera binds — `@event`, spread's `@event` key, `data-vd-on-*` — runs
|
|
139
|
+
untracked. A listener you add yourself with `addEventListener` is outside Vera: fired synchronously from
|
|
140
|
+
inside a hook it still tracks, so read through `untrack()` there.
|
|
141
|
+
|
|
101
142
|
### `!name` — a live property
|
|
102
143
|
|
|
103
144
|
Every other binding skips a write when the value matches what it last wrote. That is what keeps a
|
|
@@ -114,15 +155,27 @@ first binding still says `true`, still matches what it committed, and never writ
|
|
|
114
155
|
and the page diverge and no amount of re-rendering reconciles them. A `<select>`'s options are the
|
|
115
156
|
same shape.
|
|
116
157
|
|
|
158
|
+
A `<select>`'s selection is controlled however it is spelled — `.value`, `!value` or `.selectedIndex`, written
|
|
159
|
+
in the template or as a `spread()` key. Every binding on a select is committed when the render pass ends, so
|
|
160
|
+
its options exist whether they are static, a list, a nested template or a keyed list; the selection is re-asserted
|
|
161
|
+
on every render (its options can move under an unchanged value) and written only when the select holds a different
|
|
162
|
+
one (the write resets every option, so skipping it is what keeps a table with a select per row fast). On a
|
|
163
|
+
`<select multiple>`, `value` and `selectedIndex` each control ONE selection and a selection the user adds is kept;
|
|
164
|
+
bind `?selected=${…}` on each `<option>` to control every one. Development says so.
|
|
165
|
+
|
|
117
166
|
It is deliberately narrow, and it is a **property** binding only:
|
|
118
167
|
|
|
119
168
|
- **Not for text inputs.** Bind those with `.value` and let a person's typing stand. `!value` exists
|
|
120
169
|
and is authoritative, which is precisely why it is not the default.
|
|
121
170
|
- **Not offered for attributes or booleans.** Nothing changes those behind the renderer's back, so
|
|
122
171
|
there is nothing to re-read.
|
|
123
|
-
- **
|
|
124
|
-
|
|
125
|
-
|
|
172
|
+
- **On a component it is delivered**, exactly as `.name` is: compared against the component's current
|
|
173
|
+
value on every render and, on a difference, handed to it — a running component re-renders. An equal
|
|
174
|
+
value costs one read and renders nothing.
|
|
175
|
+
- **It yields during hydration — for a control's user state.** A click that happened before the bundle
|
|
176
|
+
landed had no handler to report it, so adoption records `value`, `checked`, `selected` and `open`
|
|
177
|
+
without writing; live semantics resume on the first state-driven render. Any other `!name` is
|
|
178
|
+
written on adoption (`!indeterminate`, which no markup can carry), and on a component delivered.
|
|
126
179
|
|
|
127
180
|
`spread({ '!checked': … })` means the same thing, and `@verajs/ssr` serializes it exactly as
|
|
128
181
|
`.checked` — a server has nothing to re-read.
|
|
@@ -149,6 +202,12 @@ What a child position does with each kind of value. These match lit-html exactly
|
|
|
149
202
|
Strings render as **text**, always. There is no path by which an interpolated value becomes markup
|
|
150
203
|
— see [Trusted HTML](#trusted-html-and-why-there-is-no-unsafehtml).
|
|
151
204
|
|
|
205
|
+
**An element whose whole content is one `${…}` belongs to that value.** `<ul>${rows}</ul>` renders its rows
|
|
206
|
+
straight into the `<ul>` with no marker nodes at all, so nodes added to that `<ul>` by other code are removed when
|
|
207
|
+
the value changes. Anywhere else a position is bracketed by two empty comments, and what sits outside them is
|
|
208
|
+
left alone. A custom element is never owned this way — a light-DOM component renders into its own children, so a
|
|
209
|
+
`${…}` inside `<my-panel>` keeps its markers and the two coexist.
|
|
210
|
+
|
|
152
211
|
### A boolean child renders the word, and JSX is the exception
|
|
153
212
|
|
|
154
213
|
`${items.length > 0 && html\`…\`}` is the ordinary conditional idiom, and when the test fails the
|
|
@@ -165,6 +224,46 @@ React's rule and where React expectations live. That is the **one** value semant
|
|
|
165
224
|
a hand-written template differ, and this warning is what meets JSX-shaped code pasted into a
|
|
166
225
|
template. `0` still renders in both, exactly as in React: the rule is about booleans, not falsiness.
|
|
167
226
|
|
|
227
|
+
### A template committed into the wrong namespace is named
|
|
228
|
+
|
|
229
|
+
An `<svg>` draws SVG content and its three HTML integration points — `<foreignObject>`, `<desc>`
|
|
230
|
+
and `<title>` — and nothing else. A template written `` html`…` ``
|
|
231
|
+
and handed across a function boundary into one is still HTML — `<path>` parsed as HTML is an
|
|
232
|
+
`HTMLUnknownElement` with the right tag name and no geometry, so a whole set of icons can vanish
|
|
233
|
+
with nothing to search for:
|
|
234
|
+
|
|
235
|
+
```js
|
|
236
|
+
const Frame = (children) => html`<svg viewBox="0 0 24 24">${children}</svg>`;
|
|
237
|
+
Frame(html`<path d="M0 0h24" />`); // silent: nothing draws
|
|
238
|
+
Frame(svg`<path d="M0 0h24" />`); // the fix — the tag is chosen where the template is WRITTEN
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
The tag is right where it was written and the call site cannot know the destination — lit-html
|
|
242
|
+
behaves the same way. **Wire `@verajs/renderer/namespaces`** and the renderer corrects it: an
|
|
243
|
+
`` html`…` `` template is then parsed in the namespace of the position it lands in, so the first line
|
|
244
|
+
above draws too (see [below](#verajsrenderernamespaces--a-template-parsed-where-it-lands)).
|
|
245
|
+
Without it, **development names it**, once per host namespace, host name, content namespace and tag. HTML content gets both remedies: `` svg`…` `` when the element was
|
|
246
|
+
meant to be SVG, and an HTML island (`<foreignObject>` in SVG, `<mtext>` in MathML) when it is
|
|
247
|
+
genuinely HTML. Tagging a custom element `` svg`…` `` would silence the message and leave the
|
|
248
|
+
element permanently un-upgraded, since custom-element upgrade is spec-gated on the HTML namespace.
|
|
249
|
+
|
|
250
|
+
The rule is a namespace MISMATCH, so MathML committed into an `<svg>` and SVG committed into a
|
|
251
|
+
`<math>` are named by it too — with their own advice, since the template's tag is already right
|
|
252
|
+
there and only the destination is wrong. It is silent where the content is correct: inside
|
|
253
|
+
`<foreignObject>`, `<desc>` and `<title>`, inside MathML's token elements, inside
|
|
254
|
+
`<annotation-xml>` carrying an HTML `encoding` — or `image/svg+xml`, MathML's own registered
|
|
255
|
+
spelling for an SVG annotation — as an ATTRIBUTE, the only form the parser reads (an `.encoding`
|
|
256
|
+
property is named), for an `<svg>` in any `<annotation-xml>`, where the parser itself puts one, and
|
|
257
|
+
for `<style>`/`<script>`, which never draw — an HTML `<style>` inside an `<svg>` applies its rules
|
|
258
|
+
perfectly well.
|
|
259
|
+
|
|
260
|
+
**In JSX this cannot happen** unless it is switched off: `@verajs/jsx` wires
|
|
261
|
+
`@verajs/renderer/namespaces` from every file it compiles (not with `inject: false` or
|
|
262
|
+
`namespaces: false`, which leave it to you), so `<Frame><path /></Frame>` works. The message is what meets a hand-written template when
|
|
263
|
+
the module is not wired, or a template built before it was — the message names that too.
|
|
264
|
+
|
|
265
|
+
The whole check folds away in production — no code and no strings.
|
|
266
|
+
|
|
168
267
|
A DOM node renders as itself, which is how a template holds something another library owns:
|
|
169
268
|
|
|
170
269
|
```js
|
|
@@ -184,9 +283,11 @@ renderInto(html`<ul>${rows.map((row) => keyed(row.id, html`<li>${row.label}</li>
|
|
|
184
283
|
```
|
|
185
284
|
|
|
186
285
|
`keyed(key, result)` tags a result with its identity, so a reorder **moves** the existing elements
|
|
187
|
-
instead of rebuilding them —
|
|
286
|
+
instead of rebuilding them — form state, scroll position and running animations survive. Focus does
|
|
287
|
+
not survive a MOVE: the platform blurs any node that is re-inserted, framework or not (pinned in the
|
|
288
|
+
browser suite), so only the elements that actually moved lose it.
|
|
188
289
|
It is its own entry because most apps never reorder a list, and the algorithm that makes reordering
|
|
189
|
-
cheap is <!--size:keyed.gzip-->
|
|
290
|
+
cheap is <!--size:keyed.gzip-->2.69 KB<!--/size:keyed.gzip--> gzipped they would otherwise carry. Importing `keyed` is the whole installation:
|
|
190
291
|
nothing registers, and there is no `wire()` call — the marker stamps each result with the strategy
|
|
191
292
|
that understands it, so a list always names its own reconciler and two strategies cannot disagree
|
|
192
293
|
about one. Lit splits `repeat` out for the same reason; the difference is that this one arrives on
|
|
@@ -199,10 +300,28 @@ than at install. Both ship from this package and bump together, so a single vers
|
|
|
199
300
|
the trap is pinning one and floating the other. `@verajs/renderer/spread` carries the same rule for
|
|
200
301
|
the same reason.
|
|
201
302
|
|
|
202
|
-
**It is additive, not a substitute.** Unlike `/
|
|
303
|
+
**It is additive, not a substitute.** Unlike `/profiler`, this entry imports nothing
|
|
203
304
|
at all — it reaches whatever renderer is present through a handful of mangling-exempt members — so
|
|
204
305
|
it is safe alongside any of them, `/hydrate` included.
|
|
205
306
|
|
|
307
|
+
<!-- D28, 2026-11-12: the full-renderer requirement below lives HERE while lists is unreleased; llms.txt documents no
|
|
308
|
+
automatic lists yet, and its lists section must carry the same sentence when lists is released. -->
|
|
309
|
+
**Experimental: automatic `.map`, `lists` and `createSelector`.** With `lists` wired —
|
|
310
|
+
`wire([renderer, lists])` — a plain `state.rows.map((row) => html`…`)` over a store array inside a render is a keyed
|
|
311
|
+
list whose rows track themselves: a field write re-renders that one row, and pushes, removals and swaps touch only what
|
|
312
|
+
moved. Rows are keyed by an item's own `id`, else by the item itself. `lists` needs the FULL renderer: wired beside a
|
|
313
|
+
bare `{ on: 'render', fn: renderInto }` its rows cannot commit themselves, so every row's change re-renders the parent,
|
|
314
|
+
and development says so once (`lists-no-renderer`). `createSelector(() => state.selected)` returns
|
|
315
|
+
`isSelected(key)`, which re-renders only the old and the new key's rows on a change. Without `lists` wired, development says so once
|
|
316
|
+
(`lists-unwired`) when such a `.map` returns templates, since rows are then matched by position; to match by position on
|
|
317
|
+
purpose, map a plain copy, `[...state.rows].map(…)`. The copy still TRACKS — spreading reads every index, so the render
|
|
318
|
+
re-runs on any item change — it opts out of keying, not of reactivity. **Hydrated, an automatic list adopts the server's rows**
|
|
319
|
+
(their nodes, and a component row's element) instead of rebuilding them; a component row is handed its `.item` AFTER it
|
|
320
|
+
upgrades — its first render may see `undefined`, so read it as `this.item?.label`. Not released; the design is still
|
|
321
|
+
being measured. **A hidden list is released when the render that hid it returns**: a component's render, or a row's
|
|
322
|
+
own render for a list nested in a row. A `.map` inside your own render-priority hook (`effect(fn, { priority: 50 })`) is a list too,
|
|
323
|
+
but one it hides is released only when that hook is torn down.
|
|
324
|
+
|
|
206
325
|
**A list is keyed because `keyed()` marked it, not because its results have a `key` property.**
|
|
207
326
|
Setting `.key` by hand no longer makes a list keyed — the marker is what carries the algorithm, so
|
|
208
327
|
it is what the renderer looks for, on the client and when adopting server markup alike.
|
|
@@ -213,6 +332,9 @@ unkeyed item in a keyed list has no identity to match on.
|
|
|
213
332
|
An unkeyed list is not wrong — it updates each position in place, which is exactly right for a list
|
|
214
333
|
whose order never changes.
|
|
215
334
|
|
|
335
|
+
One position can switch between a keyed and an unkeyed list, in either direction, and render
|
|
336
|
+
correctly — the items are the same kind of thing, and an unkeyed one simply has no key to match on.
|
|
337
|
+
|
|
216
338
|
## Preserving DOM — `hold()`
|
|
217
339
|
|
|
218
340
|
```js
|
|
@@ -231,7 +353,9 @@ parked, `0` on return, and `0` even for a node moved directly between two attach
|
|
|
231
353
|
applier does with the nodes can hold it, and lit's `cache()` cannot either. If a scroll position
|
|
232
354
|
matters, read it before the toggle and restore it after.
|
|
233
355
|
|
|
234
|
-
Anything that is not a template passes straight through — there is nothing to park for a string, a list, `null` or `false` — so `hold(editing && editor())` is safe to write.
|
|
356
|
+
Anything that is not a template passes straight through — there is nothing to park for a string, a list, `null` or `false` — so `hold(editing && editor())` is safe to write, and the editor is rebuilt when it returns: parking happens only when another held template takes its place.
|
|
357
|
+
|
|
358
|
+
**A parked template's refs keep their element** — parking is not destruction, and the element comes back. They are released when the section itself goes away, along with everything it parked; clearing the section (`null`) keeps what it parked.
|
|
235
359
|
|
|
236
360
|
It only re-adopts a template it has seen at **that same call site** — two `hold()` calls in
|
|
237
361
|
different templates are two different templates, and neither adopts the other's DOM. The other
|
|
@@ -277,22 +401,306 @@ committed in place against templates that replaced a different template.
|
|
|
277
401
|
| Import | What it adds | Ships in production |
|
|
278
402
|
| --- | --- | --- |
|
|
279
403
|
| `@verajs/renderer` | the renderer | yes |
|
|
280
|
-
| `@verajs/renderer/
|
|
404
|
+
| `@verajs/renderer/hydration` | `hydration` (wire it beside the renderer) — the first render adopts server-rendered DOM | yes |
|
|
405
|
+
| `@verajs/renderer/hydrate-slots` | `hydrateSlots` (wire it) — reads the server's light-slot format, for an app that hydrates light slots | yes |
|
|
281
406
|
| `@verajs/renderer/keyed` | `keyed(key, result)` — keyed list reconciliation | yes |
|
|
282
407
|
| `@verajs/renderer/spread` | `spread(props)` — binding names resolved at runtime | yes |
|
|
283
408
|
| `@verajs/renderer/tag` | `` tag`h1` `` — an element whose tag name is decided at runtime | yes |
|
|
284
409
|
| `@verajs/renderer/slots` | `slots` (wire it) + `slotted(host, name?)` — light-DOM `<slot>` distribution | yes |
|
|
410
|
+
| `@verajs/renderer/namespaces` | `namespaces` (wire it) — an `html` template parsed in the namespace of where it lands | yes |
|
|
411
|
+
| `@verajs/renderer/elements` | `elements` (wire it) — behavior attached to claimed elements in templates, mounted and unmounted with their instances | yes |
|
|
412
|
+
| `@verajs/renderer/portal` | `portal(target, template)` — a component draws into ANOTHER element (a modal on `document.body`), in a range of its own | yes |
|
|
413
|
+
| `@verajs/renderer/until` | `until(promise, fallback)` — a promise at a child position: the fallback, then its value | yes |
|
|
414
|
+
| `@verajs/renderer/native-elements` | `nativeElements` (wire it) — `init` on a built-in element (a `div`, a `section`…) with a custom element's lifecycle | yes |
|
|
415
|
+
| `@verajs/renderer/multi-window` | `multiWindow` (wire it) — components left in a pop-out or an iframe are released when that window closes | yes |
|
|
285
416
|
| `@verajs/renderer/profiler` | a superset that measures template churn | no — development only |
|
|
286
417
|
|
|
287
|
-
`/
|
|
288
|
-
|
|
289
|
-
|
|
418
|
+
`/profiler` re-exports the whole public API, so it is a drop-in replacement for the base import. **Never mix it
|
|
419
|
+
with `@verajs/renderer` in one app** — that loads two renderers with two template caches, and profiling while
|
|
420
|
+
rendering through the other observes an instance nothing renders into (measured: renders reported zero frames while
|
|
421
|
+
the page updated correctly). `formatReport` says so when it observed nothing, because a zero report is otherwise
|
|
422
|
+
indistinguishable from an app with nothing to optimize. **A hydrating app profiles like any other:** wire
|
|
423
|
+
`hydration` beside the profiler's renderer — `wire([renderer, hydration])` with `renderer` from
|
|
424
|
+
`@verajs/renderer/profiler` — and its adoption is profiled too.
|
|
425
|
+
|
|
426
|
+
## `@verajs/renderer/elements` — behavior on elements in templates
|
|
427
|
+
|
|
428
|
+
Attach behavior to elements *in templates* — "every `[autofocus]`", "every `<slot>`", "every
|
|
429
|
+
`<dialog open>`" — without a directive system and without touching the elements' markup. A
|
|
430
|
+
**claimant** is an ordinary insert on `'element'`: it is asked about each element of a template once,
|
|
431
|
+
when the template is first used, and answers with a shared behavior object or `undefined`. Every
|
|
432
|
+
instance of that template then runs the behavior's `mount` once its render has finished, and
|
|
433
|
+
`unmount` at teardown with whatever `mount` returned.
|
|
434
|
+
|
|
435
|
+
The example is a real gap. Measured on Chromium, Firefox and WebKit, the first `autofocus` element
|
|
436
|
+
rendered after page load takes focus and **every later one is ignored** — so the second form an app
|
|
437
|
+
shows, an edit dialog or a step two, never gets the focus its markup asks for. Five lines fix it:
|
|
438
|
+
|
|
439
|
+
<!-- recipe -->
|
|
440
|
+
```js
|
|
441
|
+
import { wire, html } from '@verajs/core';
|
|
442
|
+
import { renderer, renderInto } from '@verajs/renderer';
|
|
443
|
+
import { elements } from '@verajs/renderer/elements';
|
|
444
|
+
|
|
445
|
+
/** One shared object for every claimed element of every instance. */
|
|
446
|
+
const autofocus = { mount: (element) => element.focus() };
|
|
447
|
+
|
|
448
|
+
wire([
|
|
449
|
+
renderer,
|
|
450
|
+
elements,
|
|
451
|
+
{ on: 'element', fn: (el) => (el.hasAttribute('autofocus') ? autofocus : undefined), priority: 50 },
|
|
452
|
+
]);
|
|
453
|
+
|
|
454
|
+
const step = (n) => html`<form><label>Step ${n} <input autofocus name=${'step' + n}></label></form>`;
|
|
455
|
+
const [first, second] = [document.createElement('div'), document.createElement('div')];
|
|
456
|
+
document.body.append(first, second);
|
|
457
|
+
renderInto(step(1), first);
|
|
458
|
+
document.activeElement.blur();
|
|
459
|
+
renderInto(step(2), second); // a second form, later: focused, where the platform alone would not
|
|
460
|
+
if (document.activeElement.name !== 'step2') throw new Error('the second form did not take focus');
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
What a claimant can rely on:
|
|
464
|
+
|
|
465
|
+
- **It is asked about the TEMPLATE's element, once.** The element is inert: its tag and its
|
|
466
|
+
**static** attributes are real, bindings are not applied yet — `autofocus=${x}` cannot be claimed on
|
|
467
|
+
`x`. Claim the attribute's presence and decide in `mount`. SVG and MathML elements are asked too.
|
|
468
|
+
- **`create(element, adopted)` runs as each instance is created** — before its first update writes
|
|
469
|
+
anything, and before the instance is connected anywhere — so the element holds exactly the static
|
|
470
|
+
children the template wrote, each binding position still the empty text it parsed as. It is the one
|
|
471
|
+
moment those can be told apart; `@verajs/renderer/slots` records a host's static children there.
|
|
472
|
+
Nothing is kept from it, and it is optional.
|
|
473
|
+
- **`mount(element, { root, adopted })` runs once the render that created the instance has
|
|
474
|
+
finished** — in the same end-of-render pass as refs, in document order, so a claim that MOVES an
|
|
475
|
+
element does so after refs above it saw it in place (measure in `mount`, not in a ref) — so the whole tree is in place and connected if its container is — a nested instance is
|
|
476
|
+
inserted only when its outer one is, which is why it does not run straight after the instance's own
|
|
477
|
+
update. `root` is the render's container. An instance discarded before its render ends never mounts.
|
|
478
|
+
- **`unmount(kept, element)` runs once, at teardown** — a template swapped out, a keyed row dropped, a
|
|
479
|
+
list shrunk, a container cleared — and only when `mount` returned something. **`hold()` is not
|
|
480
|
+
teardown**: a parked instance keeps its mount and is not mounted again when it returns.
|
|
481
|
+
- **Several claimants may claim one element**; each gets its own `create`/`mount`/`unmount`, in wire order.
|
|
482
|
+
- **No updates.** A behavior that must react to values is a binding or an applier (`_$apply$`), not a
|
|
483
|
+
claim — which is what keeps claims off the hot path.
|
|
484
|
+
- **A throwing `create`, `mount` or `unmount` is reported, never raised** — the rule a `&ref` follows:
|
|
485
|
+
to the app's `'error'` chain with the component, else as uncaught (`reportError`), and the render,
|
|
486
|
+
the other claims and the teardown carry on. Every throw is reported. A claim whose `create` threw is
|
|
487
|
+
dropped for that instance — it never mounts or unmounts — and its element stays as the template
|
|
488
|
+
built it.
|
|
489
|
+
- **Wire it before anything renders**, like `slots`: a template asks its claimants when it is first
|
|
490
|
+
used, and a claimant wired later never hears about templates already built — development says so
|
|
491
|
+
at `wire`, for this module and every other that decides per template (`namespaces`, `slots`). An app that wires no
|
|
492
|
+
claimant pays nothing; one that does pays one walk per new template, and one short walk per
|
|
493
|
+
instance of a template something claimed.
|
|
494
|
+
|
|
495
|
+
## `@verajs/renderer/until` — a promise in a template
|
|
496
|
+
|
|
497
|
+
```js
|
|
498
|
+
import { until } from '@verajs/renderer/until';
|
|
499
|
+
|
|
500
|
+
define('x-user', () => {
|
|
501
|
+
const user = fetchUser(); // made ONCE, in the setup
|
|
502
|
+
return () => html`<p>${until(user, html`<em>loading…</em>`)}</p>`;
|
|
503
|
+
});
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
It shows the fallback, then what the promise resolves to.
|
|
507
|
+
|
|
508
|
+
- **The same promise again** (any re-render) keeps what is shown: no flash, no second subscription. Make the promise in
|
|
509
|
+
the setup, as above; one written inline in the template is a new promise, a new request, every render.
|
|
510
|
+
- **A new promise** shows the fallback again, and the old one's late answer is dropped, so a slow first request never
|
|
511
|
+
overwrites a newer one.
|
|
512
|
+
- **Removed before it settles,** the answer is dropped.
|
|
513
|
+
- **Not a promise:** shown at once.
|
|
514
|
+
- **A rejection** keeps the fallback, and the browser reports it, as any unhandled rejection: in the console with its
|
|
515
|
+
stack, and as an `unhandledrejection` event, which error monitoring hears. To SHOW an error, pass the caught promise —
|
|
516
|
+
a caught promise resolves to whatever the handler returns:
|
|
517
|
+
|
|
518
|
+
```js
|
|
519
|
+
html`<p>${until(user.catch(() => html`<b>couldn't load</b>`), html`<em>loading…</em>`)}</p>`
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
That also keeps the browser from reporting an error you handled. For a refreshing state too, use `resource()` from
|
|
523
|
+
`@verajs/store/resource`, which carries `loading`, `value` and `error`.
|
|
524
|
+
- **On a server** it renders the fallback and waits for nothing, and a rejection there is consumed: the server never shows
|
|
525
|
+
the result, and an unhandled rejection would end a Node process. Hydration draws the fallback again and the value
|
|
526
|
+
replaces it.
|
|
527
|
+
|
|
528
|
+
`until` is built on the `_$child$` protocol below; core and the renderer carry nothing for it.
|
|
529
|
+
|
|
530
|
+
## `@verajs/renderer/multi-window` — components in the windows your page opens
|
|
531
|
+
|
|
532
|
+
A component moved into another window's document — a pop-out (`window.open`) or an iframe — is kept by core, state and
|
|
533
|
+
all, and comes back the same way. When that window CLOSES with components still inside, nothing tells them: they stay
|
|
534
|
+
subscribed to this window's stores, alive and running, for the life of the page. Wire `multiWindow` and they are
|
|
535
|
+
released then:
|
|
536
|
+
|
|
537
|
+
```js
|
|
538
|
+
import { wire } from '@verajs/core';
|
|
539
|
+
import { renderer } from '@verajs/renderer';
|
|
540
|
+
import { multiWindow } from '@verajs/renderer/multi-window';
|
|
541
|
+
|
|
542
|
+
wire([renderer, multiWindow]);
|
|
543
|
+
|
|
544
|
+
const popup = window.open('', 'panel');
|
|
545
|
+
popup.document.body.append(panel); // pop out: kept
|
|
546
|
+
popup.addEventListener('pagehide', () => document.body.append(panel)); // optional: bring it home as it closes
|
|
547
|
+
```
|
|
548
|
+
|
|
549
|
+
- **What is released:** every component of this core still in the closed window's document, shadow roots included —
|
|
550
|
+
one moved there, one built there while it was out, one appended there directly. Each runs its cleanups once, and no
|
|
551
|
+
write wakes it again.
|
|
552
|
+
- **When:** at that window's final `pagehide`, on this window's NEXT task, so your own `pagehide` handler runs first; a
|
|
553
|
+
panel it moves home is no longer in the closed document and survives.
|
|
554
|
+
- **Not released:** a back/forward-cached hide (`persisted`), which can come back.
|
|
555
|
+
- **Cost:** nothing on any normal path (core hears a move into another document on its cold cross-window path only), and
|
|
556
|
+
nothing at all for an app that does not wire it. It imports nothing.
|
|
557
|
+
|
|
558
|
+
In the platform's words: a `window.open` window is an *auxiliary browsing context*, an iframe's a *child navigable*,
|
|
559
|
+
moving a node into another document is *adoption* (core's `'adopted'` insert point), and a closing window's document is
|
|
560
|
+
*unloaded*.
|
|
561
|
+
|
|
562
|
+
## `@verajs/renderer/native-elements` — `init` on a built-in element
|
|
563
|
+
|
|
564
|
+
A custom element tells core when it leaves the page and when it comes back — its `connectedCallback` and
|
|
565
|
+
`disconnectedCallback` — so a component that calls `init(this)` there is torn down when it is removed, set up again when
|
|
566
|
+
it returns, and kept when it is merely moved. A built-in element (a `div`, a `section`) given to `init` tells nobody: by
|
|
567
|
+
itself it is drawn and stays reactive, but it is never released when removed. Wire `nativeElements` and it gets exactly
|
|
568
|
+
the custom element's lifecycle. (Not to be confused with `@verajs/renderer/elements`, above, which attaches behavior to
|
|
569
|
+
elements *inside* templates.)
|
|
570
|
+
|
|
571
|
+
<!-- recipe -->
|
|
572
|
+
```js
|
|
573
|
+
import { wire, init, html, createStore } from '@verajs/core';
|
|
574
|
+
import { renderer } from '@verajs/renderer';
|
|
575
|
+
import { nativeElements } from '@verajs/renderer/native-elements';
|
|
576
|
+
|
|
577
|
+
wire([renderer, nativeElements]);
|
|
578
|
+
|
|
579
|
+
const state = createStore({ count: 0 });
|
|
580
|
+
const panel = document.createElement('section');
|
|
581
|
+
document.body.append(panel);
|
|
582
|
+
init(panel, () => () => html`<button @click=${() => state.count++}>${state.count}</button>`);
|
|
583
|
+
|
|
584
|
+
panel.remove(); // torn down: its effects' cleanups run, it leaves every store
|
|
585
|
+
document.body.append(panel); // set up again, fresh — as a custom element re-added
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
- **Removed:** torn down, exactly as a custom element's removal (cleanups run, nothing it read keeps it alive).
|
|
589
|
+
- **Re-attached:** set up again — its setup runs again, so what the setup created starts fresh.
|
|
590
|
+
- **Moved** in one operation (`append`/`insertBefore` of a connected element), or **into another window's document** (a
|
|
591
|
+
popped-out panel): kept, with its state.
|
|
592
|
+
- **Given `init` before it is on the page:** its setup waits for its first connect, as a custom element's does — a host
|
|
593
|
+
built off the page and never attached is never set up and holds nothing.
|
|
594
|
+
|
|
595
|
+
**For a few hosts, not for volume:** a built-in host carries a little more than a custom element (its closed root and two
|
|
596
|
+
small nodes), so it costs a little more to create and to collect. Use it for the handful of roots, islands and panels
|
|
597
|
+
an app has; anything created in volume — rows, items, repeated widgets — belongs in a custom element.
|
|
598
|
+
|
|
599
|
+
**How it hears:** each host gets a CLOSED shadow root holding a default `<slot>` (its light content renders exactly as
|
|
600
|
+
before) and a tiny custom element whose own callbacks fire when its host is attached, moved or removed — the same in
|
|
601
|
+
Chromium, Firefox and WebKit. The root is closed, so `host.shadowRoot` stays `null` and selectors see the host's children
|
|
602
|
+
as before.
|
|
603
|
+
|
|
604
|
+
**Not supported** (said by name in development; the element still renders, and is never released when removed):
|
|
290
605
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
606
|
+
- elements that cannot hold a shadow root — `ul`, `li`, `table`, `button` and the rest; supported are `div`, `section`,
|
|
607
|
+
`article`, `aside`, `header`, `footer`, `main`, `nav`, `p`, `span`, `blockquote`, `h1`–`h6` and `body`;
|
|
608
|
+
- an element that already has a shadow root — including one `init` attached from a `shadow` option, or from the app's
|
|
609
|
+
`renderer({ shadow })` default (an app with a shadow default has no supported built-in hosts);
|
|
610
|
+
- the host's own later `attachShadow()` (or declarative shadow DOM) — it now has one; development says why.
|
|
611
|
+
|
|
612
|
+
One thing changes for a supported host: a DIRECT child carrying a `slot` attribute (`<span slot="title">`) renders
|
|
613
|
+
nowhere, since the host's root has only a default `<slot>` (the same in every engine; a deeper descendant with one is
|
|
614
|
+
unaffected) — development says so, naming the host. Document CSS is otherwise unaffected — child and structural selectors, `:empty`, `:has()`, inheritance
|
|
615
|
+
and layout match a host without it.
|
|
616
|
+
|
|
617
|
+
Also: a built-in element built in a document with no window (`document.implementation.createHTMLDocument`, a
|
|
618
|
+
`DOMParser` result) is not set up; and a component left inside a window when that window closes (an iframe removed, a
|
|
619
|
+
pop-out closed, with the component still in it) is the app's to remove.
|
|
620
|
+
|
|
621
|
+
## `@verajs/renderer/portal` — drawing into another element
|
|
622
|
+
|
|
623
|
+
A component's own render goes into its own root. To draw somewhere ELSE — a modal or a toast on `document.body`, a
|
|
624
|
+
tooltip in an overlay layer — call `portal(target, template)` in its setup:
|
|
625
|
+
|
|
626
|
+
<!-- recipe -->
|
|
627
|
+
```js
|
|
628
|
+
import { wire, define, html, createStore } from '@verajs/core';
|
|
629
|
+
import { renderer } from '@verajs/renderer';
|
|
630
|
+
import { portal } from '@verajs/renderer/portal';
|
|
631
|
+
|
|
632
|
+
wire([renderer]);
|
|
633
|
+
|
|
634
|
+
const state = createStore({ open: true, title: 'Saved' });
|
|
635
|
+
define('x-toast', () => {
|
|
636
|
+
portal(document.body, () => (state.open ? html`<div role="status">${state.title}</div>` : ''));
|
|
637
|
+
return () => html`<button @click=${() => (state.open = !state.open)}>toggle</button>`;
|
|
638
|
+
});
|
|
639
|
+
|
|
640
|
+
const toast = document.createElement('x-toast');
|
|
641
|
+
document.body.append(toast); // the button in the component, the status line at the end of <body>
|
|
642
|
+
toast.remove(); // the status line goes with it
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
- **A range of its own.** It appends two comment markers to `target` and draws between them, so any number of portals
|
|
646
|
+
share one target and none touches what was there before it.
|
|
647
|
+
- **The render's slot.** It is drawn when the component's render is (a keyed `.map` keeps its rows with their items, and
|
|
648
|
+
layout effects see it drawn), it updates from what it reads like any render, and what a draw made and no longer
|
|
649
|
+
reaches — a hidden automatic list, a computed — is released as a render's is.
|
|
650
|
+
- **Owned by the component.** Removing the component takes its content and its markers out of `target`; a component
|
|
651
|
+
that `persist`s takes them out while it is away and draws them again when it is back — appended at the END of
|
|
652
|
+
`target` again, so its order among the target's other children (two open modals) can change. Moving the component into
|
|
653
|
+
another window's document (a pop-out) leaves the portal where it is — `target` is where it was asked to draw — and it
|
|
654
|
+
stays live.
|
|
655
|
+
- **Light DOM.** It draws into `target` itself, never into a shadow root: into a shadow host, the content is the host's
|
|
656
|
+
light content, placed by its `<slot>`. Styles are therefore `target`'s, not the component's — a shadow component's
|
|
657
|
+
`static styles` do not reach a portal's content (style it in the document, or with its own `<style>`). Events bubble
|
|
658
|
+
from the content up through `target`'s ancestors, not through the component.
|
|
659
|
+
- **The client only.** On a server a portal registers nothing: the server renders the component's own template, and
|
|
660
|
+
hydration adopts that and then draws the portal once.
|
|
661
|
+
- **Call it in a setup.** It belongs to the component being set up; after an `await` in an async setup none is, and it
|
|
662
|
+
throws, as `effect` does (`no-owner`).
|
|
663
|
+
|
|
664
|
+
It keeps `@verajs/core` external in every build (its draw is one of core's effects; inlined, it would be a second core),
|
|
665
|
+
so a CDN page's import map names `@verajs/core` beside it — as it already does for `@verajs/store`.
|
|
666
|
+
|
|
667
|
+
## `@verajs/renderer/namespaces` — a template parsed where it lands
|
|
668
|
+
|
|
669
|
+
A template's namespace is normally fixed by its tag: `` html`…` `` is HTML wherever it goes, which is
|
|
670
|
+
why a shape handed into an `<svg>` needs `` svg`…` ``. Wire this module and the renderer instead
|
|
671
|
+
parses an `html` template **in the namespace of the position it is committed into** — the way the
|
|
672
|
+
browser's own parser treats markup written inside an `<svg>`:
|
|
673
|
+
|
|
674
|
+
<!-- recipe -->
|
|
675
|
+
```js
|
|
676
|
+
import { html, wire } from '@verajs/core';
|
|
677
|
+
import { renderer, renderInto } from '@verajs/renderer';
|
|
678
|
+
import { namespaces } from '@verajs/renderer/namespaces';
|
|
679
|
+
|
|
680
|
+
wire([renderer, namespaces]);
|
|
681
|
+
|
|
682
|
+
const Frame = (children) => html`<svg viewBox="0 0 24 24">${children}</svg>`;
|
|
683
|
+
const host = document.createElement('div');
|
|
684
|
+
renderInto(Frame([html`<title>Close</title>`, html`<path d="M0 0h24"></path>`]), host);
|
|
685
|
+
|
|
686
|
+
if (host.querySelector('path').namespaceURI !== 'http://www.w3.org/2000/svg') throw new Error('not SVG');
|
|
687
|
+
if (host.querySelector('title').namespaceURI !== 'http://www.w3.org/2000/svg') throw new Error('not SVG');
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
The answer comes from the parser, not from a list: SVG's camelCase names keep their case,
|
|
691
|
+
`<foreignObject>`, `<desc>` and `<title>` hold HTML again, MathML's token elements likewise, and the
|
|
692
|
+
same strings committed into a `<div>` stay HTML. Under a MathML parent the parser's answer depends on
|
|
693
|
+
the child as well — `<svg>` inside `<annotation-xml>`, `<mglyph>` inside `<mi>` — so there it is asked
|
|
694
|
+
with the template's own first tag.
|
|
695
|
+
|
|
696
|
+
- **`@verajs/jsx` wires it for you**, from every file it compiles — JSX cannot write `` svg`…` ``.
|
|
697
|
+
- **Wire it before anything renders.** It applies to a template when the template is first built, so
|
|
698
|
+
one built earlier keeps the namespace it was built in; development names that case.
|
|
699
|
+
- **`svg`/`mathml` tags still work** and still decide their own namespace — wiring this changes only
|
|
700
|
+
`html` templates.
|
|
701
|
+
- **What it costs**: its own bundle, only when wired. The renderer's update path is untouched; a
|
|
702
|
+
template is resolved once per instance it creates, measured at parity with explicit tags on
|
|
703
|
+
Chromium, Firefox and WebKit.
|
|
296
704
|
|
|
297
705
|
## `@verajs/renderer/slots` — light-DOM slots
|
|
298
706
|
|
|
@@ -318,7 +726,7 @@ Given this markup:
|
|
|
318
726
|
|
|
319
727
|
<!-- recipe -->
|
|
320
728
|
```js
|
|
321
|
-
import { init,
|
|
729
|
+
import { init, wire, html } from '@verajs/core';
|
|
322
730
|
import { renderer } from '@verajs/renderer';
|
|
323
731
|
import { slots, slotted } from '@verajs/renderer/slots';
|
|
324
732
|
|
|
@@ -328,13 +736,10 @@ customElements.define(
|
|
|
328
736
|
'my-card',
|
|
329
737
|
class extends HTMLElement {
|
|
330
738
|
connectedCallback() {
|
|
331
|
-
init(this)
|
|
332
|
-
render(
|
|
333
|
-
() => html`<article>
|
|
739
|
+
init(this, () => () => html`<article>
|
|
334
740
|
<header><slot name="header" @slotchange=${(e) => this.onHeader(e.target)}>Untitled</slot></header>
|
|
335
741
|
<main><slot>Nothing here yet.</slot></main>
|
|
336
|
-
</article>`
|
|
337
|
-
);
|
|
742
|
+
</article>`); // LIGHT DOM — no shadow option
|
|
338
743
|
}
|
|
339
744
|
/** Written exactly as it would be against a shadow root, and it runs in both. */
|
|
340
745
|
onHeader(slot) {
|
|
@@ -363,9 +768,38 @@ console.log(slotted(card, 'header').length); // 1
|
|
|
363
768
|
> DIFFERENT renderer — lit-html — where there is no seam to find.) The assignment follows
|
|
364
769
|
the platform's own rules — elements to the slot their `slot` attribute names, text to the default
|
|
365
770
|
slot, fallback shown only while a slot is unassigned and restored when it empties, direct children
|
|
366
|
-
only.
|
|
367
|
-
|
|
368
|
-
|
|
771
|
+
only. **Every node goes to the slot its own `slot` names** — including the nodes a binding in the
|
|
772
|
+
page's template writes, so ``${items.map((i) => html`<li slot=${i.where}>…</li>`)}`` distributes
|
|
773
|
+
exactly as the same markup written out by hand, and keeps doing so as the list changes. Live:
|
|
774
|
+
appending, removing, or re-slotting children redistributes automatically. Re-renders leave slotted
|
|
775
|
+
nodes in place, identity intact, so focus and input values survive.
|
|
776
|
+
|
|
777
|
+
**Server-rendered and hydrated.** `@verajs/ssr` emits already-distributed markup — each filled slot's
|
|
778
|
+
content between two comments, exactly as this module leaves it on the client — and states the light
|
|
779
|
+
tree on each host. A hydrating page adopts it in place, nested components included, with one more
|
|
780
|
+
module wired, which only an app that hydrates light slots loads:
|
|
781
|
+
|
|
782
|
+
```js
|
|
783
|
+
import { hydrateSlots } from '@verajs/renderer/hydrate-slots';
|
|
784
|
+
wire([renderer, hydration, slots, hydrateSlots]);
|
|
785
|
+
```
|
|
786
|
+
|
|
787
|
+
Without it, a server-rendered host with light content is left exactly as served — never cleared — and the console
|
|
788
|
+
names what to wire (`hydration-slots`); a host the server stated empty (`1:`) hydrates without it.
|
|
789
|
+
**Wire `slots` on the server too:** a server without it writes no light-tree statement, so every
|
|
790
|
+
component it rendered is taken for client-made and renders fresh on the client — its server markup kept, hidden, as
|
|
791
|
+
unassigned light content — and no warning is possible, because the client cannot tell the two apart. **Serve the server's HTML unmodified, comments included:** a
|
|
792
|
+
minifier that strips comments removes the slots' markers, and the host renders fresh, as React, Lit
|
|
793
|
+
and Solid treat a missing marker. The light-tree statement carries a format number, so render and
|
|
794
|
+
hydrate with matching releases of `@verajs/ssr` and `@verajs/renderer`: a page in another format
|
|
795
|
+
renders fresh, its content kept, and the warning says so. A component host carrying no statement was
|
|
796
|
+
made on the client, and gets a client first render rather than an adoption.
|
|
797
|
+
|
|
798
|
+
**Measured, including where it still differs.** `tests/browser/slots-conformance.test.js` runs whole
|
|
799
|
+
component lifecycles through a real shadow root and through this module on Chromium, Firefox and
|
|
800
|
+
WebKit, comparing the composed tree and element identity after every step, and every scenario
|
|
801
|
+
matches — slot forwarding (a `<slot>` placed inside another light component shows what the outer slot
|
|
802
|
+
shows) and `hold()` inside content one template places into another component included.
|
|
369
803
|
|
|
370
804
|
**A `<slot>` inside another slot's fallback works**, and takes over at the moment that fallback
|
|
371
805
|
becomes visible — the same thing the platform does, verified by layout on three engines. Slots are
|
|
@@ -389,18 +823,17 @@ it work would mean writing framework attributes into the user's own markup.
|
|
|
389
823
|
|
|
390
824
|
**A node added AFTER the first render joins its slot with full native semantics** — bare text and
|
|
391
825
|
attribute-less elements included, in document order, exactly as a shadow root would assign them.
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
positions you can name, since a distributed child is no longer a direct child of the host.
|
|
826
|
+
A light host's own render occupies one range of its children, bracketed by the renderer's own
|
|
827
|
+
comments, so a node added outside that range is knowably the user's: added before it, it joins
|
|
828
|
+
ahead of everything the host was given; after it, behind. `slot=""`/`slot="name"` still route, they
|
|
829
|
+
are simply not required. Inside a slot, use `before()`/`after()` on what is already there (see
|
|
830
|
+
below) and the new node joins at that place in light order.
|
|
831
|
+
|
|
832
|
+
Two things are worth knowing: whitespace appended to a light host suppresses the default fallback,
|
|
833
|
+
which is parity (a shadow root does the same), and re-slotting a node (`slot="a"` → `"b"`) rejoins
|
|
834
|
+
in light-tree order rather than arrival order. Every position you can reach orders exactly as the
|
|
835
|
+
platform does — what light has fewer of is positions you can name, since a distributed child is no
|
|
836
|
+
longer a direct child of the host.
|
|
404
837
|
|
|
405
838
|
**Cloning a RENDERED light component does not work, and cannot.** `cloneNode(true)` copies a
|
|
406
839
|
light host's children — which after a render are the component's own output with the user's slotted
|
|
@@ -409,26 +842,46 @@ rendered tree ends up nested inside its own default slot. A shadow component clo
|
|
|
409
842
|
opposite reason: `cloneNode` does not copy a shadow root, so the clone re-renders and its light
|
|
410
843
|
children are still just its light children.
|
|
411
844
|
|
|
412
|
-
Nothing can detect this —
|
|
413
|
-
the original user content was consumed at the first render,
|
|
414
|
-
duplicate a component, clone the SOURCE markup and let the copy
|
|
415
|
-
a live instance. This matters most to anything that duplicates components as an operation: an editor
|
|
845
|
+
Nothing can detect this — after a render the user's content and the component's output are the
|
|
846
|
+
same kind of node in the same tree, and the original user content was consumed at the first render,
|
|
847
|
+
so there is nothing to recover. **To duplicate a component, clone the SOURCE markup and let the copy
|
|
848
|
+
render itself**, rather than cloning a live instance. This matters most to anything that duplicates components as an operation: an editor
|
|
416
849
|
canvas, a repeater, a drag-to-copy.
|
|
417
850
|
|
|
418
851
|
**`slotted(host, name?)`** is the component-internal accessor — what the user assigned to a slot,
|
|
419
852
|
answered identically in shadow mode (native assignment) and light mode (the capture map). Omit
|
|
420
853
|
`name` for the default slot. Component authors reach for this; app users do not.
|
|
421
854
|
|
|
855
|
+
**When the assignment is current.** Whatever a template does is distributed by the end of that render — an outer
|
|
856
|
+
template changing a component's children included — so code measuring slotted content right after a render (a layout
|
|
857
|
+
effect, `getBoundingClientRect`) sees the new assignment. A light host changed directly by your code
|
|
858
|
+
(`host.append(node)`, `node.slot = 'x'`) is redistributed by the next microtask, or at once when its slotted content is
|
|
859
|
+
read through the slots API (`slotted()`, `slot.assignedNodes()`).
|
|
860
|
+
|
|
861
|
+
### Where the `<slot>` element is
|
|
862
|
+
|
|
863
|
+
**A slot with content steps out of the page, and its content stands in its place. A slot with
|
|
864
|
+
nothing assigned stays in the page, showing its fallback.** So the rendered tree reads the way the
|
|
865
|
+
composed tree of a shadow root reads: where a slot has content, that content is a child of the
|
|
866
|
+
slot's parent; where it has none, the fallback is the `<slot>` element's own children, and the
|
|
867
|
+
HTML standard's UA stylesheet gives every `<slot>` `display: contents`, so the element itself adds no
|
|
868
|
+
box. The switch happens each time a slot gains its first node or loses its last one.
|
|
869
|
+
|
|
870
|
+
Two things follow. `querySelector('slot')` finds exactly the slots currently showing their
|
|
871
|
+
fallback, and none that have content — so reach a slot through `&ref` or `event.target`, never by
|
|
872
|
+
selector. And a structural selector written against your template (`:first-child`, `> h2`) sees the
|
|
873
|
+
slotted content where a filled slot stood, which is where a reader sees it.
|
|
874
|
+
|
|
422
875
|
### The `<slot>` element is still the component's handle on the slot
|
|
423
876
|
|
|
424
877
|
A slot is not only a position, and a component that keeps up with what it was given binds to the
|
|
425
878
|
element itself. All of that means here what it means in a shadow root:
|
|
426
879
|
|
|
427
880
|
```js
|
|
428
|
-
|
|
881
|
+
return () => html`<header>
|
|
429
882
|
<slot name=${section} &ref=${(el) => (this.slot = el)}
|
|
430
883
|
@slotchange=${(e) => wire(e.target.assignedElements())}>Nothing yet</slot>
|
|
431
|
-
</header
|
|
884
|
+
</header>`;
|
|
432
885
|
```
|
|
433
886
|
|
|
434
887
|
- **`@slotchange`** fires on first assignment and on every change after it — and only then, so a
|
|
@@ -436,15 +889,38 @@ render(() => html`<header>
|
|
|
436
889
|
`assignedNodes()` are asserted against real shadow DOM, which is the oracle for this. It fires
|
|
437
890
|
for a slot whose rendering is currently displaced too (assignment is independent of rendering),
|
|
438
891
|
exactly as native does for a slot that is not on screen.
|
|
439
|
-
- **`node.assignedSlot` answers
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
892
|
+
- **`node.assignedSlot` answers light slots too.** The platform's getter knows only shadow roots, so slots replaces it
|
|
893
|
+
once per window, at that window's first light host. It answers for the nodes slots placed, from what distribution
|
|
894
|
+
already records (nothing is written per node), and defers to the getter it replaced for every other node, so
|
|
895
|
+
shadow-DOM nodes, other copies of Vera, and other code that patched it answer as before. One case stays native: a node
|
|
896
|
+
created in another window (an iframe's parent) and placed into a light host here reads `null` unless its own window
|
|
897
|
+
also has a light host. The forward reads carry the same fact: `slot.assignedNodes()` through a `&ref`, or
|
|
898
|
+
`slotted(host, name)` from outside.
|
|
899
|
+
- **Only a component that needs slotting pays for it.** One with no light content and no `<slot>` gets no observer and
|
|
900
|
+
no hidden element; a component is observed from its first `<slot>`. So a child appended by hand to a component that
|
|
901
|
+
has neither shows until a slot renders — native hides it. `observeSlots: 'eager'` observes a component
|
|
902
|
+
from its first render instead — `init({ host: this, observeSlots: 'eager' }, setup)` — as a shadow root follows
|
|
903
|
+
every host; `wire([renderer, slots({ observeSlots: 'eager' })])` makes that every light component's default (its own
|
|
904
|
+
`observeSlots` wins), at an observer per component. The default, `'lazy'` (paired as HTML's `loading` pairs them),
|
|
905
|
+
starts at the first `<slot>` or light child and is fully correct for everything a template renders. A value it does
|
|
906
|
+
not have reads as `'lazy'` — the built-in default, even where the app's is `'eager'`, as `foreignNodes` does — and
|
|
907
|
+
development says so.
|
|
908
|
+
- **A component you remove by hand and put back follows the hand-edit rule.** What its outer template then writes into
|
|
909
|
+
it is distributed by the component's own observer, a microtask later, not by the end of that template's render; the
|
|
910
|
+
slots API reads it at once (it flushes), and a direct DOM read in the same task can still see the old content.
|
|
911
|
+
- **A `<slot>` removed by hand unassigns its content, as in a shadow root.** Its content shows in the next slot of that
|
|
912
|
+
name, or nowhere: through the slot's own `remove()` / `replaceWith()`, or by removing its parent or an ancestor (a
|
|
913
|
+
microtask later, the hand-edit rule). One spelling cannot work: a slot WITH content has stepped out of the page (its
|
|
914
|
+
region stands in its place), so `slot.parentNode` is `null` and `parentNode.removeChild(slot)` has nothing to call.
|
|
915
|
+
- **Insert `<slot>`s through the template, or observe the component eagerly.** On a component observed lazily (the
|
|
916
|
+
default), a `<slot>` inserted by hand is not one the template rendered, so it stays empty, where a shadow root uses it
|
|
917
|
+
at once. With `observeSlots: 'eager'` it is claimed like the template's own. Rendering the slot conditionally
|
|
918
|
+
(`${open ? html`<slot></slot>` : null}`) works in every mode.
|
|
919
|
+
- **Bind `slotchange` directly — do not count on it reaching the host.** In a shadow root one listener
|
|
920
|
+
on the root hears every slot by bubbling. Here a slot with content is out of the document, so the
|
|
921
|
+
event fired as it fills has no tree to climb, while the one fired as it empties — the slot is back
|
|
922
|
+
in the page by then — does climb: a host-level listener hears some changes and not others. Use
|
|
923
|
+
`@slotchange` on each slot, which hears all of them and hands you the right `event.target`.
|
|
448
924
|
- **`assignedNodes(options)` / `assignedElements(options)`** answer from the live assignment,
|
|
449
925
|
through `event.target` or a `&ref`. With nothing assigned, `{ flatten: true }` gives the fallback
|
|
450
926
|
actually on screen — slottables only, so a comment you wrote into fallback content is not in it,
|
|
@@ -456,139 +932,88 @@ render(() => html`<header>
|
|
|
456
932
|
root the same line works, because there nothing moves. `before()`/`after()` route through the
|
|
457
933
|
node's own current parent, so they are correct in both modes, and the content lands in the order
|
|
458
934
|
you asked for. This is the sharpest difference between the two modes and the easiest to hit.
|
|
459
|
-
- **A
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
935
|
+
- **A slotted component is MOVED into its slot, and a Vera component is not torn down by it.** Each
|
|
936
|
+
slotted node goes from where it is to where it is shown in ONE DOM operation, which core treats as a
|
|
937
|
+
move: a component that called `init()` keeps its effects, state and setup through it — nothing runs
|
|
938
|
+
twice, as nothing runs twice under native slotting, where nothing moves at all. A custom element
|
|
939
|
+
that is not a Vera component gets the platform's callbacks for a move: `disconnectedCallback` and
|
|
940
|
+
then `connectedCallback`.
|
|
941
|
+
- **A node no slot takes stays connected, and is not rendered — as under native slots.** A light
|
|
942
|
+
host has no second tree to hide it in, so it waits in a hidden container the host is given for
|
|
943
|
+
the purpose, `<ins hidden data-vm-unassigned>`, its FIRST child: a component in it keeps running (its
|
|
944
|
+
effects stay live), it is still in the host's tree for `querySelector`, as a native unassigned
|
|
945
|
+
light child is, and when a
|
|
946
|
+
slot for it appears it moves there in one operation and is kept. The container is there only
|
|
947
|
+
while it holds something, so a host whose content is all assigned has no extra child. When it is
|
|
948
|
+
there, it is a child of your host like any other: `host.children`, `:scope > *`, `:first-child`,
|
|
949
|
+
`:nth-child()` and `:empty` see it — write `:scope > :not([data-vm-unassigned])` where that matters.
|
|
950
|
+
It stays hidden whatever a stylesheet says (an inline `display: none !important` beside `hidden`).
|
|
951
|
+
It is a standard element, so it is valid HTML around any content, and `:defined`: a lazy loader
|
|
952
|
+
or a "wait until every element is defined" check never waits on it.
|
|
469
953
|
- **`name` can be a binding.** `<slot name=${section}>` routes by the name it actually has, and
|
|
470
954
|
re-routes if it changes between renders.
|
|
471
955
|
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
and takes whole strategies — so if you would rather have the *shadow tree's own structure* (the
|
|
477
|
-
slot element present, selectable, `:first-child`-countable, made layout-invisible by the same
|
|
478
|
-
`display: contents` the UA stylesheet gives real slots), you can wire a strategy that keeps it.
|
|
479
|
-
This one is complete enough to run — and it runs, in CI, as written:
|
|
480
|
-
|
|
481
|
-
<!-- recipe -->
|
|
482
|
-
```js
|
|
483
|
-
import { init, render, wire, html } from '@verajs/core';
|
|
484
|
-
import { renderer } from '@verajs/renderer';
|
|
485
|
-
|
|
486
|
-
/** Distribution that KEEPS the <slot>: content moves INSIDE it, fallback shows when it is empty. */
|
|
487
|
-
const slotsInTree = {
|
|
488
|
-
name: 'my-app/slots-in-tree',
|
|
489
|
-
on: 'slot',
|
|
490
|
-
priority: 50,
|
|
491
|
-
fn(slot, root, name) {
|
|
492
|
-
if (root.nodeType !== 1) return null; // a shadow root keeps native slotting
|
|
493
|
-
const host = root;
|
|
494
|
-
const fallback = [...slot.childNodes];
|
|
495
|
-
const isMine = (n) =>
|
|
496
|
-
n.nodeType === 1 ? (n.getAttribute('slot') ?? '') === name
|
|
497
|
-
: name === '' && n.nodeType === 3 && n.data.trim() !== '';
|
|
498
|
-
let shown = -1;
|
|
499
|
-
const fill = () => {
|
|
500
|
-
for (const n of [...host.childNodes]) if (isMine(n)) slot.append(n);
|
|
501
|
-
const assigned = [...slot.childNodes].filter((n) => !fallback.includes(n));
|
|
502
|
-
for (const n of fallback) (assigned.length ? n.remove() : slot.append(n));
|
|
503
|
-
observer.takeRecords(); // our own moves are not the user's
|
|
504
|
-
if (assigned.length !== shown) {
|
|
505
|
-
shown = assigned.length;
|
|
506
|
-
slot.dispatchEvent(new Event('slotchange', { bubbles: true })); // real ancestors — it CLIMBS
|
|
507
|
-
}
|
|
508
|
-
};
|
|
509
|
-
const observer = new MutationObserver(fill);
|
|
510
|
-
fill();
|
|
511
|
-
observer.observe(host, { childList: true, subtree: true });
|
|
512
|
-
return { _$park$: () => { observer.disconnect(); for (const n of [...slot.childNodes]) if (!fallback.includes(n)) host.append(n); } };
|
|
513
|
-
},
|
|
514
|
-
};
|
|
515
|
-
|
|
516
|
-
wire([renderer, slotsInTree]);
|
|
517
|
-
document.head.insertAdjacentHTML('beforeend', '<style>slot{display:contents}</style>');
|
|
518
|
-
|
|
519
|
-
customElements.define('tree-card', class extends HTMLElement {
|
|
520
|
-
connectedCallback() {
|
|
521
|
-
init(this);
|
|
522
|
-
render(() => html`<article><slot name="header">Untitled</slot></article>`);
|
|
523
|
-
}
|
|
524
|
-
});
|
|
525
|
-
|
|
526
|
-
const card = document.createElement('tree-card');
|
|
527
|
-
card.innerHTML = '<h2 slot="header">Hello</h2>';
|
|
528
|
-
document.body.append(card);
|
|
529
|
-
await new Promise((resolve) => requestAnimationFrame(resolve));
|
|
530
|
-
|
|
531
|
-
/** Every documented boundary of the shipped strategy, working: */
|
|
532
|
-
let heard = 0;
|
|
533
|
-
card.addEventListener('slotchange', () => heard++); // a HOST-level listener — bubbling exists here
|
|
534
|
-
if (!card.querySelector('slot')) throw new Error('querySelector finds the slot');
|
|
535
|
-
if (card.querySelector('h2').parentElement.localName !== 'slot') throw new Error('reverse lookup');
|
|
536
|
-
card.querySelector('h2').remove();
|
|
537
|
-
await new Promise((resolve) => setTimeout(resolve, 0));
|
|
538
|
-
if (card.querySelector('article').textContent !== 'Untitled') throw new Error('fallback returns');
|
|
539
|
-
if (heard !== 1) throw new Error('slotchange bubbled to the host');
|
|
540
|
-
```
|
|
541
|
-
|
|
542
|
-
The trade is the one the platform itself makes: this is the shadow tree's structure, so the
|
|
543
|
-
`<slot>` now appears in your host's serialized markup (as it appears in a `shadowRoot`'s), your
|
|
544
|
-
component CSS can select it — and structural selectors written against the template see it as the
|
|
545
|
-
child it is, because selectors follow the tree, not layout. Wire it *instead of* `slots` — the
|
|
546
|
-
seam is single-registrant, and wiring both says so in development, by name.
|
|
547
|
-
|
|
548
|
-
What this recipe deliberately does not do is the audited module's territory: light-tree ordering
|
|
549
|
-
under re-slots and prepends, duplicate-name handover, nested slots in fallbacks, dynamic
|
|
550
|
-
`name=${…}`, SSR and hydration. It is a starting point you own, not a drop-in peer — the measured
|
|
551
|
-
design for a full sibling lives with the maintainers.
|
|
552
|
-
|
|
553
|
-
**The one thing a light-DOM slot cannot carry is presentation** — `class`, `style`, `id` and other
|
|
554
|
-
plain attributes. A light host has no second tree, so the slot element is not rendered and there is
|
|
555
|
-
nothing for them to apply to, while in a shadow root they do apply. Put them on a real element
|
|
556
|
-
around the slot. Development builds say so, naming the attribute, rather than leaving it to be
|
|
557
|
-
found.
|
|
956
|
+
**A `<slot>` carries presentation only while it shows its fallback** — `class`, `style`, `id` and
|
|
957
|
+
other plain attributes. Once it has content it steps out of the page and its attributes go with it,
|
|
958
|
+
while in a shadow root they keep applying. Put them on a real element around the slot. Development
|
|
959
|
+
builds say so, naming the attribute, rather than leaving it to be found.
|
|
558
960
|
|
|
559
961
|
Additive like `keyed`/`spread`: it imports no renderer and reaches the one present through the wired
|
|
560
962
|
seam, so it is safe beside any renderer entry on a CDN page. The entry is
|
|
561
|
-
**<!--size:slots.gzip-->
|
|
562
|
-
`@verajs/renderer` itself carries
|
|
563
|
-
|
|
564
|
-
|
|
963
|
+
**<!--size:slots.gzip-->6.22 KB<!--/size:slots.gzip-->** gzipped and only apps importing it pay;
|
|
964
|
+
`@verajs/renderer` itself carries only generic hooks it plugs into. It is also Node-safe to import —
|
|
965
|
+
it imports nothing and touches no DOM until something renders — so a universal app can wire it on
|
|
966
|
+
both sides.
|
|
565
967
|
|
|
566
|
-
## `@verajs/renderer/
|
|
968
|
+
## `@verajs/renderer/hydration`
|
|
567
969
|
|
|
568
970
|
<!-- recipe -->
|
|
569
971
|
```js
|
|
570
|
-
import {
|
|
571
|
-
|
|
972
|
+
import { wire } from '@verajs/core';
|
|
973
|
+
import { renderer } from '@verajs/renderer';
|
|
974
|
+
import { hydration } from '@verajs/renderer/hydration';
|
|
572
975
|
|
|
573
|
-
|
|
574
|
-
|
|
976
|
+
wire([renderer, hydration]);
|
|
977
|
+
```
|
|
575
978
|
|
|
576
|
-
The first render into a container that already has
|
|
577
|
-
same template: node identity is preserved, listeners attach, and
|
|
578
|
-
Hydration here is **markerless** — server HTML carries no framework comments
|
|
579
|
-
|
|
979
|
+
One more module wired beside the renderer — nothing else changes. The first render into a container that already has
|
|
980
|
+
children **adopts** them as server output of the same template: node identity is preserved, listeners attach, and
|
|
981
|
+
updates mutate the adopted nodes. Hydration here is **markerless** — server HTML carries no framework comments (light
|
|
982
|
+
slots aside: each filled slot's content sits between two, see [`/slots`](#verajsrendererslots--light-dom-slots)), and
|
|
983
|
+
the client repairs its own anchors into the adopted DOM.
|
|
984
|
+
|
|
985
|
+
**Server-rendered HTML must be hydrated.** A client that does not wire `hydration` renders beside the server's markup
|
|
986
|
+
— two copies, the server's dead — because a first render appends, and markup without a marker cannot be recognized.
|
|
987
|
+
The one case that can be: with slots wired, the server states every component host it renders, so on a client
|
|
988
|
+
without `hydration` a host stated empty (no light content) is cleared and rendered once, and a host holding the page's
|
|
989
|
+
light content stands exactly as served with a coded error (`hydration-unwired`; development names what to wire); development warns
|
|
990
|
+
once per page. A host that arrives with no children at all is simply rendered fresh, whatever its statement says, since
|
|
991
|
+
there is nothing to duplicate or lose. Its `data-vm-light` attribute is then left in place. That is harmless: only a
|
|
992
|
+
host's first render ever reads it, and a server re-states it on every render, so a copy of the live page (an editor's
|
|
993
|
+
save, a devtools copy of `outerHTML`) carrying it is no different from served markup.
|
|
580
994
|
|
|
581
995
|
Any disagreement with the server markup clears the container (keeping `<style data-vm-sheet="styles">` tags)
|
|
582
996
|
and renders fresh, so correctness never depends on the server output being right. A DOM node at a
|
|
583
997
|
child position is the one thing the server cannot have rendered; it is inserted without giving up
|
|
584
998
|
adoption of everything around it.
|
|
585
999
|
|
|
586
|
-
**A fallback warns in
|
|
587
|
-
`<p>` and found `<div>`"*, *"`<ul>` contains `<li>`, which the template does
|
|
1000
|
+
**A fallback warns in every build, naming the first place the two renders disagreed** — development
|
|
1001
|
+
spells it out, *"expected `<p>` and found `<div>`"*, *"`<ul>` contains `<li>`, which the template does
|
|
1002
|
+
not describe"*; production prints the kind and the node it found. It is said once per kind of
|
|
1003
|
+
disagreement per hydration pass, so a list whose every row disagrees the same way is one line. The page
|
|
588
1004
|
is correct either way, which is the point of the fallback and also why it needs saying: that
|
|
589
1005
|
container's markup was just thrown away, and with nothing observable to notice, the only symptom is
|
|
590
|
-
a first paint that is slower than the one you paid a server render for. An attribute
|
|
591
|
-
|
|
1006
|
+
a first paint that is slower than the one you paid a server render for. An attribute is **read** during
|
|
1007
|
+
adoption and written only if it disagrees — a right one costs no write, a wrong one is repaired — and
|
|
1008
|
+
neither is a fallback.
|
|
1009
|
+
|
|
1010
|
+
**Form state stands.** A form control's `.value`, `.checked` and `.selected`, a `!name` on a built-in
|
|
1011
|
+
element and a `<select>`'s selection are recorded, not written, so whatever the user typed before the
|
|
1012
|
+
script arrived is kept (a `!name` then compares on the next render and takes over, as it always does).
|
|
1013
|
+
**Whoever writes an element's content owns its verification.** A custom element's children are its own
|
|
1014
|
+
render: when the template writes nothing inside the tag, adoption leaves them to the component (what the
|
|
1015
|
+
template does write inside it is compared as usual). And an element whose whole content is one `${…}`
|
|
1016
|
+
adopts as that value's range, with no marker put in.
|
|
592
1017
|
|
|
593
1018
|
**A fallback costs one container, not the page.** Adoption is decided per container, so components
|
|
594
1019
|
hydrating into their own roots are independent: one that disagrees rebuilds and warns, and every
|
|
@@ -601,23 +1026,22 @@ required in the server markup, and one in the server markup that your template d
|
|
|
601
1026
|
a disagreement. A comment renders nothing, so neither direction changes what a reader sees; matching
|
|
602
1027
|
on them would only cost every commented template its adoption.
|
|
603
1028
|
|
|
604
|
-
On a CDN page,
|
|
605
|
-
|
|
1029
|
+
On a CDN page, load `vera-renderer-hydration.min.js` beside `vera-renderer.min.js` and wire both. Apps that never
|
|
1030
|
+
hydrate download none of this.
|
|
606
1031
|
|
|
607
1032
|
### Importing this in Node
|
|
608
1033
|
|
|
609
1034
|
**`@verajs/renderer` needs a DOM to be imported at all**, not merely to render. It captures
|
|
610
|
-
`document` at module scope and
|
|
611
|
-
allocation per instance — so `import '@verajs/renderer'` on a server throws
|
|
1035
|
+
`document` at module scope (and creates its scratch fragment there) — so `import '@verajs/renderer'` on a server throws
|
|
612
1036
|
`ReferenceError: document is not defined` before any of your code runs. The same is true of
|
|
613
|
-
`/
|
|
1037
|
+
`/profiler`, and of `@verajs/jsx/standalone`, which contains a renderer.
|
|
614
1038
|
|
|
615
1039
|
This is worth stating because [`@verajs/router`](../router#node-and-ssr) documents the opposite
|
|
616
1040
|
about itself, and the asymmetry is easy to read the wrong way. The rest of the family is Node-safe:
|
|
617
1041
|
`@verajs/core`, `@verajs/inserts`, `@verajs/store` and `/collections`, `@verajs/router`,
|
|
618
1042
|
`@verajs/styles`, `@verajs/autoloader`, `@verajs/jsx` (the transform), `@verajs/ssr` — **and
|
|
619
|
-
`@verajs/renderer/keyed`, `/spread` and `/
|
|
620
|
-
parent entry does.
|
|
1043
|
+
`@verajs/renderer/keyed`, `/spread`, `/tag`, `/hydration` and `/hydrate-slots`**, which hold no DOM of their own even
|
|
1044
|
+
though their parent entry does.
|
|
621
1045
|
|
|
622
1046
|
In a universal app, hand the renderer in rather than importing it in shared code — which is what
|
|
623
1047
|
`examples/kitchen-sink/wiring.js` does, taking it as a parameter so the server can pass `null`.
|
|
@@ -629,7 +1053,7 @@ Spread a props object onto an element, with names resolved at runtime.
|
|
|
629
1053
|
|
|
630
1054
|
<!-- recipe -->
|
|
631
1055
|
```js
|
|
632
|
-
import { init, createStore,
|
|
1056
|
+
import { init, createStore, wire, html } from '@verajs/core';
|
|
633
1057
|
import { renderer } from '@verajs/renderer';
|
|
634
1058
|
import { spread } from '@verajs/renderer/spread';
|
|
635
1059
|
|
|
@@ -639,16 +1063,17 @@ customElements.define(
|
|
|
639
1063
|
'x-field',
|
|
640
1064
|
class extends HTMLElement {
|
|
641
1065
|
connectedCallback() {
|
|
642
|
-
init(this,
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
1066
|
+
init({ host: this, shadow: 'open' }, () => {
|
|
1067
|
+
const state = createStore({ disabled: false });
|
|
1068
|
+
const props = {
|
|
1069
|
+
id: 'email', // attribute
|
|
1070
|
+
placeholder: 'you@example.com', // "
|
|
1071
|
+
'.value': '', // property
|
|
1072
|
+
'?disabled': state.disabled, // boolean attribute
|
|
1073
|
+
onInput: (e) => console.log(e.target.value), // event — @input works too
|
|
1074
|
+
};
|
|
1075
|
+
return () => html`<input ${spread(props)} />`;
|
|
1076
|
+
});
|
|
652
1077
|
}
|
|
653
1078
|
}
|
|
654
1079
|
);
|
|
@@ -689,7 +1114,7 @@ html`<calendar-day ${props({ date, events })}></calendar-day>`
|
|
|
689
1114
|
<calendar-day date={date} events={events} /> // JSX only: bare props ARE props on a component tag
|
|
690
1115
|
```
|
|
691
1116
|
|
|
692
|
-
One function, both surfaces — JSX compiles `{...x}` to `spread(x)`, and `spread()`
|
|
1117
|
+
One function, both surfaces — JSX compiles `{...x}` to `spread(x)`, and `spread()` recognizes an
|
|
693
1118
|
already-branded result, so the two spellings are literally the same call. In JSX the bag is
|
|
694
1119
|
optional altogether: on a dash-named tag a bare prop compiles to the `.name` binding directly
|
|
695
1120
|
(`@verajs/jsx`'s README has the two attribute carve-outs), so `props()` is the template's
|
|
@@ -715,7 +1140,7 @@ Three rules, each earned:
|
|
|
715
1140
|
|
|
716
1141
|
Nothing to declare on the other side — no `static properties`, no props argument. A component that
|
|
717
1142
|
calls `init()` finds every bound property on `this`, **reactively**: reading `this.date` in a
|
|
718
|
-
render tracks it, the parent's next commit re-renders, and a store or `
|
|
1143
|
+
render tracks it, the parent's next commit re-renders, and a store or `signal()` passed through stays
|
|
719
1144
|
live because it arrives by identity. The full reception contract — including what happens when the
|
|
720
1145
|
component's module loads *after* the parent rendered — is documented with `init()` in
|
|
721
1146
|
`@verajs/core`'s README; this package's half is the delivery:
|
|
@@ -770,12 +1195,11 @@ written `@event` bindings behave too.
|
|
|
770
1195
|
|
|
771
1196
|
### What it costs, and why it is a separate entry
|
|
772
1197
|
|
|
773
|
-
`@verajs/renderer` grows **
|
|
774
|
-
measured 2026-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
dated; re-measure the same way if it matters.
|
|
1198
|
+
`@verajs/renderer` grows **25 B** gzipped for the protocol this uses, whether or not you import it —
|
|
1199
|
+
measured 2026-09-28 by deleting the `_$apply$` branch and its teardown guard (a released ref must not
|
|
1200
|
+
write `.value = null` onto an object that applies itself) and rebuilding, as a **difference** rather
|
|
1201
|
+
than a pair of totals — the totals move with every change to this package and the difference does not.
|
|
1202
|
+
Nothing regenerates it, so it is dated; re-measure the same way if it matters.
|
|
779
1203
|
The entry itself is **<!--size:spread.gzip-->1.60 KB<!--/size:spread.gzip-->** gzipped, and only apps
|
|
780
1204
|
that import it pay for that.
|
|
781
1205
|
|
|
@@ -788,7 +1212,7 @@ small and fast, and it is why neither this renderer nor lit-html has spread buil
|
|
|
788
1212
|
|
|
789
1213
|
The renderer itself holds only a protocol: a value at element position carrying `_$apply$` applies
|
|
790
1214
|
itself. Everything else lives in this entry, which imports nothing — not even from the renderer — so
|
|
791
|
-
it loads alongside any renderer that
|
|
1215
|
+
it loads alongside any renderer that honors the protocol, including your own.
|
|
792
1216
|
|
|
793
1217
|
## `@verajs/renderer/profiler`
|
|
794
1218
|
|
|
@@ -848,17 +1272,66 @@ renderInto(html`<div .innerHTML=${trustedMarkup}></div>`, host);
|
|
|
848
1272
|
|
|
849
1273
|
Greppable, obviously yours, reviewable as the security decision it is. Sanitize first
|
|
850
1274
|
(`DOMPurify.sanitize`) unless the markup is genuinely your own, and put it on an element whose
|
|
851
|
-
children nothing else binds — the renderer owns the content of elements it renders into.
|
|
1275
|
+
children nothing else binds — the renderer owns the content of elements it renders into. `@verajs/ssr`
|
|
1276
|
+
serializes it into the served page and hydration adopts it, behaving as the assignment does: a `<script>` in it
|
|
1277
|
+
never runs and a `<template shadowrootmode>` never attaches, on either side.
|
|
1278
|
+
|
|
1279
|
+
**Only a tagged template is a template.** A value renders as markup only when its strings came from a tagged
|
|
1280
|
+
template literal — an array owning `raw`, which nothing from `JSON.parse` can be. Data shaped like a template (an
|
|
1281
|
+
API field an attacker turned into `{"strings": [...]}`, a real template sent through JSON, or a hand-built
|
|
1282
|
+
`html([markup])`) renders as the text any object does, `[object Object]`, here and in `@verajs/ssr` alike — and here,
|
|
1283
|
+
in development, with a warning each time a new one arrives. Never a throw: the value is attacker-controlled, and a throw would hand over the subtree. The
|
|
1284
|
+
check runs where a template is first built, so a cached template pays nothing. (An ordinary object interpolated
|
|
1285
|
+
as a child renders as `String(object)`, as before; one that cannot convert — a parsed `"toString"` key — throws,
|
|
1286
|
+
as it does in React. Render a field, not a raw API object.)
|
|
1287
|
+
|
|
1288
|
+
**Development tells you; production pays nothing.** Misuse the renderer can see in a template's own source, or in an
|
|
1289
|
+
obviously wrong call, is caught in development: a template that cannot work as written throws there (a name
|
|
1290
|
+
expression, below; a value in TAG position, `<${x}>`, which needs a tag value from `@verajs/renderer/tag`;
|
|
1291
|
+
`renderInto` without a container; `keyed` without a template; a template ending inside a tag; a binding beside or
|
|
1292
|
+
inside an element in an SVG/MathML `<title>` or `<style>`, which this renderer reads as text, or inside the obsolete
|
|
1293
|
+
`<xmp>`, `<noembed>`, `<noframes>` and `<plaintext>`, which the parser does), and a mistake that still renders
|
|
1294
|
+
but not as meant is a `[vera]` warning (a self-closed `<div />`, a boolean child, a value that cannot
|
|
1295
|
+
listen, `@clik`, a binding on an element the parser drops, content in the wrong namespace, a repeated key) — said
|
|
1296
|
+
once where the mistake is in the template's source, and each time it happens where it is in a value (a boolean
|
|
1297
|
+
child, a value that cannot listen, a repeated key). None of
|
|
1298
|
+
it exists in the production build — those bundles are byte-for-byte what they would be without it.
|
|
1299
|
+
|
|
1300
|
+
**An attribute name cannot be an expression.** `<p data-${key}="1">` (or `<b ${name}="x">`, or
|
|
1301
|
+
`<p ${key}-x>`) throws in development when the template is first used — `@verajs/ssr` refuses it in every
|
|
1302
|
+
build — because the parser reads a name before any value exists. (Production pays nothing for the check:
|
|
1303
|
+
a template is fixed source, so its first development render finds it.) A name known only at runtime is a spread —
|
|
1304
|
+
`${spread({ [`data-${key}`]: '1' })}` — which refuses what a runtime name must not become (an inline handler,
|
|
1305
|
+
`srcdoc`, a `javascript:` URL); in development the error shows that rewrite for your template.
|
|
1306
|
+
|
|
1307
|
+
**Security: a bound URL cannot be a `javascript:` URL, and a bound `srcdoc` is refused.** A value
|
|
1308
|
+
bound where a browser *navigates* — `href`, `src`, `action`, `formaction`, `xlink:href` or `data`,
|
|
1309
|
+
as the attribute or as its property — is refused when it parses as a `javascript:` URL, and the
|
|
1310
|
+
attribute is removed. The same holds for an SVG animation's `to`, `from`, `by` and `values` (every item
|
|
1311
|
+
of a `values` list), on any element and whatever `attributeName` says: `<animate>`/`<set>` write their
|
|
1312
|
+
value onto the attribute they animate, `href` included, and Chromium, Firefox and WebKit all run a
|
|
1313
|
+
`javascript:` URL set on a link that way when it is clicked. It is read the way the URL Standard reads
|
|
1314
|
+
a scheme, so `" jAvA\tscript:"` is caught as surely as `javascript:`, and it is judged on the whole JOINED value, so `href="java${x}"` is
|
|
1315
|
+
caught too; the statics you write are yours and are never refused on their own. A value that is not a
|
|
1316
|
+
string is converted ONCE and the string checked is the string written, so an object whose `toString`
|
|
1317
|
+
changes its answer cannot pass as one URL and land as another. A custom element's property of the same
|
|
1318
|
+
name (`<my-chart .data=${rows}>`) is its own business: an object arrives untouched, and only a string is
|
|
1319
|
+
checked. A bound `srcdoc`
|
|
1320
|
+
*attribute* is refused outright, because it renders its value as an HTML document —
|
|
1321
|
+
`.srcdoc=${trusted}` is the deliberate spelling, exactly as `.innerHTML` is. There is no opt-out for
|
|
1322
|
+
URLs. `@verajs/ssr` applies the same rule, so a server never serves a link the client refuses.
|
|
1323
|
+
Development builds name each refusal.
|
|
852
1324
|
|
|
853
1325
|
**Security: spread refuses the injection sinks.** The `.innerHTML` posture above rests on the
|
|
854
1326
|
template spelling being greppable, obviously yours, and reviewable — three properties a spread key
|
|
855
1327
|
does not have, because spread names arrive at runtime inside a props object that is often built
|
|
856
1328
|
from data. So `spread()` refuses `.innerHTML`/`!outerHTML` property keys, the `srcdoc` attribute,
|
|
857
|
-
|
|
858
|
-
function remains the documented event spelling and still works),
|
|
859
|
-
|
|
1329
|
+
any inline-handler attribute name (`onclick` and friends, any casing — `on` + Capital with a
|
|
1330
|
+
function remains the documented event spelling and still works), and — as a template binding is —
|
|
1331
|
+
a `javascript:` URL on a key a browser navigates (`href`, `.href` and the rest), on the client AND
|
|
1332
|
+
in the SSR serializer alike. A key's verdict is decided once, when it first appears, not per render. Development builds name each refused key and the sanctioned template spelling.
|
|
860
1333
|
If you genuinely need one of these dynamically, write the binding in the template where a reviewer
|
|
861
|
-
can see it
|
|
1334
|
+
can see it — for `srcdoc`, the property: `.srcdoc=${trusted}`.
|
|
862
1335
|
|
|
863
1336
|
## `@verajs/renderer/tag`
|
|
864
1337
|
|
|
@@ -902,7 +1375,7 @@ component: `@verajs/jsx` consumes it into `keyed(…)` for both spellings, and a
|
|
|
902
1375
|
`H({ key })` drops it and says so in development, because a key marks a template for reconciliation
|
|
903
1376
|
and this call *returns* one rather than being one.
|
|
904
1377
|
|
|
905
|
-
**`dangerouslySetInnerHTML` is the one React name a tag cannot
|
|
1378
|
+
**`dangerouslySetInnerHTML` is the one React name a tag cannot honor, and that is a security
|
|
906
1379
|
property rather than a gap.** A tag reaches its element through `/spread`, whose names are only
|
|
907
1380
|
known at runtime — which is exactly what makes that sink unreviewable — so `/spread` refuses
|
|
908
1381
|
`.innerHTML` outright. Write the element directly, with the value sanitized first:
|
|
@@ -928,7 +1401,7 @@ life of three defects.
|
|
|
928
1401
|
writing tests for it.
|
|
929
1402
|
- HTML only. There is no `svg`/`mathml` equivalent yet.
|
|
930
1403
|
|
|
931
|
-
<!--size:tag.gzip-->2.
|
|
1404
|
+
<!--size:tag.gzip-->2.36 KB<!--/size:tag.gzip--> gzipped, which includes `/spread` — the factory
|
|
932
1405
|
needs it to apply props whose names it cannot know. Additive, like `/spread` and unlike the other
|
|
933
1406
|
entries: it inlines no renderer internals, so it is safe alongside any of them.
|
|
934
1407
|
|
|
@@ -950,18 +1423,29 @@ BOOLEAN_ATTRIBUTES.has('disabled'); // true — the names the tag entry toggles
|
|
|
950
1423
|
|
|
951
1424
|
The renderer holds no directive system. It holds a **protocol**, at the two positions worth
|
|
952
1425
|
extending, and everything built on it is an ordinary package the renderer knows nothing about —
|
|
953
|
-
`@verajs/renderer/spread` is the proof, at
|
|
1426
|
+
`@verajs/renderer/spread` is the proof, at 25 B of protocol in this bundle and its own weight only
|
|
954
1427
|
for apps that import it.
|
|
955
1428
|
|
|
956
1429
|
| position | brand | called as |
|
|
957
1430
|
| --- | --- | --- |
|
|
958
|
-
| element — `<div ${value}>` | `_$apply$` | `value._$apply$(element, part)` |
|
|
959
|
-
| child — `<div>${value}</div>` | `_$child$` | `value._$child$(part, previous)` |
|
|
1431
|
+
| element — `<div ${value}>` | `_$apply$` | `value._$apply$(element, part, untracked, adopting)` |
|
|
1432
|
+
| child — `<div>${value}</div>` | `_$child$` | `value._$child$(part, previous, adopting)` |
|
|
1433
|
+
|
|
1434
|
+
`adopting` is `true` exactly once, while `hydration` adopts server markup: leave form state
|
|
1435
|
+
alone, and adopt what the server rendered at the position or replace it — an applier that ignores the flag
|
|
1436
|
+
renders, which replaces. (`untracked` is how an applier runs someone else's code without subscribing the
|
|
1437
|
+
render — see core's `untrack`.)
|
|
960
1438
|
|
|
961
1439
|
A child-position value carrying `_$child$` applies itself. It is handed the part and whatever it
|
|
962
1440
|
returned last time **at that part**, and calls `part._$commit$(value)` to render content. That is
|
|
963
1441
|
the whole surface: `until()` is nine lines against it.
|
|
964
1442
|
|
|
1443
|
+
Both kinds apply **mid-commit** — `_$apply$` has to, because properties must reach an element before it
|
|
1444
|
+
is inserted and upgraded. So an element an applier receives may not be in its document yet: a template
|
|
1445
|
+
with no custom element is cloned from the browser's inert template document and inserted after its
|
|
1446
|
+
values commit. Read the realm lazily (`element.ownerDocument.defaultView` when it is needed, not at apply
|
|
1447
|
+
time), or use a ref, which runs once the element is in place.
|
|
1448
|
+
|
|
965
1449
|
```js
|
|
966
1450
|
/** Hoisted — the applier's identity is its own continuity key. */
|
|
967
1451
|
function applyUntil(part, previous) {
|
|
@@ -980,7 +1464,7 @@ renderInto(html`<p>${until(fetchUser(), html`<em>loading…</em>`)}</p>`, host);
|
|
|
980
1464
|
Three rules, each of which is a real trap:
|
|
981
1465
|
|
|
982
1466
|
- **Hoist the applier.** Written as an object-literal method it is a new function per call, so the
|
|
983
|
-
part can never
|
|
1467
|
+
part can never recognize it and `previous` is always `undefined`. Its identity is what keeps two
|
|
984
1468
|
appliers at one part from reading each other's state.
|
|
985
1469
|
- **Continuity lives in the return value**, not in an applier instance. That is what makes this a
|
|
986
1470
|
protocol rather than a framework — no base class, no `directive()` factory, no lifecycle.
|
|
@@ -1026,9 +1510,11 @@ The check costs the hot path nothing: it sits after the template branch, and a t
|
|
|
1026
1510
|
common object at a child position — returns before ever reading it, so only arrays, nodes and
|
|
1027
1511
|
appliers pay a property read. Measured with no runtime difference distinguishable from noise.
|
|
1028
1512
|
|
|
1029
|
-
The whole protocol is **
|
|
1030
|
-
whose it is, the save/restore in `_$commit$` that
|
|
1031
|
-
|
|
1513
|
+
The whole protocol is **134 B gzipped** (measured 2026-09-28 by deleting it and rebuilding) — the
|
|
1514
|
+
check, the two fields holding an applier's state and whose it is, the save/restore in `_$commit$` that
|
|
1515
|
+
stops an applier's own rendering from destroying its continuity, running a commit that arrives after
|
|
1516
|
+
the render returned as a render of the container that attached it (so it builds in that container's document and
|
|
1517
|
+
its refs run once it is done), and the `_$detach$` call.
|
|
1032
1518
|
|
|
1033
1519
|
## Animating things in and out
|
|
1034
1520
|
|
|
@@ -1081,7 +1567,7 @@ Directives other renderers ship, and what replaces them here.
|
|
|
1081
1567
|
| --- | --- |
|
|
1082
1568
|
| `repeat()` | `keyed()` |
|
|
1083
1569
|
| `cache()` | `hold()` |
|
|
1084
|
-
| `
|
|
1570
|
+
| `signal()` | an element-position expression, `<input ${myRef}>` |
|
|
1085
1571
|
| `ifDefined()` | built in — `null`/`undefined` remove an attribute |
|
|
1086
1572
|
| `classMap()` / `styleMap()` | build the string: `class="base ${extra}"` |
|
|
1087
1573
|
| `guard()` | reactivity already skips unchanged work |
|